---
title: Link Overlay
package: "@chakra-ui/layout"
image: "components/link-overlay.svg"
description: "Link overlay is a semantic component used to wrap elements (cards, blog post,
articles, etc.) in a link."
---

Link overlay provides a semantic way to wrap elements (cards, blog post,
articles, etc.) in a link.

When you need to link an entire component or card, it can be tempting to wrap it
within `<a href="...">` and think you're done. This is considered **unsemantic
and incorrect** because the component or card could contain other clickable
elements or links (tags, timestamps, buttons).

> [According to the specification](https://www.w3.org/TR/html5/text-level-semantics.html#the-a-element),
> an `<a>` element’s content model specifically states that an `<a>` cannot
> contain any interactive descendants (button, anchors, input, etc).

The `LinkOverlay` component aims to solve this by overlaying one link on top of
the component or card, and then elevating the remaining links on top of it.

<ComponentLinks
  theme={{ componentName: "link-overlay" }}
  github={{ package: "layout" }}
  npm={{ package: "@chakra-ui/layout" }}
/>

<carbon-ad></carbon-ad>

## Import

```js
import { LinkBox, LinkOverlay } from "@chakra-ui/react"
```

## Usage

Wrap the container within a `LinkBox` and use the `LinkOverlay` as a child of it
or around the title's content.

```jsx
<LinkBox as="article" maxW="sm" p="5" borderWidth="1px" rounded="md">
  <Box as="time" dateTime="2021-01-15 15:30:00 +0000 UTC">
    13 days ago
  </Box>
  <Heading size="md" my="2">
    <LinkOverlay href="#">
      New Year, New Beginnings: Smashing Workshops & Audits
    </LinkOverlay>
  </Heading>
  <Text>
    Catch up on what’s been cookin’ at Smashing and explore some of the most
    popular community resources.
  </Text>
</LinkBox>
```

### Nested Links

The `LinkBox` lifts any nested links to the top using `z-index` to ensure proper
keyboard navigation between links.

> Use the keyboard to test how focus ring moves within the article

```jsx
<LinkBox as="article" maxW="sm" p="5" borderWidth="1px" rounded="md">
  <Box as="time" dateTime="2021-01-15 15:30:00 +0000 UTC">
    13 days ago
  </Box>
  <Heading size="md" my="2">
    <LinkOverlay href="#">
      New Year, New Beginnings: Smashing Workshops & Audits
    </LinkOverlay>
  </Heading>
  <Text mb="3">
    Catch up on what’s been cookin’ at Smashing and explore some of the most
    popular community resources.
  </Text>
  <Box as="a" color="teal.400" href="#" fontWeight="bold">
    Some inner link
  </Box>
</LinkBox>
```

## Usage with Routing Library

To add support for external libraries like Next.js' or gatsby `Link`, you can
wrap them around the `LinkOverlay` or use the `as` prop (for reach and react
router)

```jsx live=false
import NextLink from "next/link"

function Example() {
  return (
    <LinkBox as="article">
      <h2>
        <NextLink href="#" passHref>
          <LinkOverlay>Some blog post</LinkOverlay>
        </NextLink>
      </h2>
      <p>
        As a side note, using quotation marks around an attribute value is
        required only if this value is not a valid identifier.
      </p>
      <a href="#">Some inner link</a>
    </LinkBox>
  )
}
```

## Caveat

One of the side-effects for this technique is that the content can't be
"selectable" (i.e with a pointing device), however this seems to be pretty
trivial compared to the benefits!

## Props

The `LinkBox` component composes the `Box` component.

The `LinkOverlay` component composes the `chakra.a` in addition to these props:

<PropsTable of="LinkOverlay" />
